GobiUIMMgmtAPI.h

/*===========================================================================
FILE: 
   GobiUimMgmtAPI.h

DESCRIPTION:
   Sierra Wireless UIM APIs

Copyright (C) 2014 Sierra Wireless Incorporated. All rights reserved.
                   Sierra Wireless Proprietary/GTDR
==========================================================================*/

#ifndef GobiUimMgmtAPI_H
#define GobiUimMgmtAPI_H
/*=========================================================================*/
// Definitions
/*=========================================================================*/
#ifdef GOBIAPI_EXPORTS
        #define IMPORTGOBI extern "C" __declspec( dllexport )   
#else  //GOBIAPI_EXPORTS
        #ifdef __cplusplus
                /* C++ callable DLL */
                #define IMPORTGOBI extern "C" __declspec( dllimport )   
        #else
                /* C callable DLL */
                #define IMPORTGOBI __declspec( dllimport )
        #endif
#endif //GOBIAPI_EXPORTS

// Calling convention for API
#define GOBICALLBACK __stdcall
#define GOBICMAPI __stdcall

#ifdef __cplusplus
   extern "C" {
#endif


/*=========================================================================*/
// Structs
/*=========================================================================*/
//QMI_UIM_GET_CARD_STATUS_RESP
typedef struct 
{
        BYTE app_type;  //• 0 – Unknown
                                        //• 1 – SIM card
                                        //• 2 – USIM application
                                        //• 3 – RUIM card
                                        //• 4 – CSIM application
                                        //• 5 – ISIM application
                                        //Other values are reserved for the future
                                        //and are to be handled as “Unknown”.
        BYTE app_state; //• 0 – Unknown
                                        //• 1 – Detected
                                        //• 2 – PIN1 or UPIN is required
                                        //• 3 – PUK1 or PUK for UPIN is required
                                        //• 4 – Personalization state must be checked
                                        //• 5 – PIN1 is blocked
                                        //• 6 – Illegal
                                        //• 7 – Ready
        BYTE perso_state;//• 0 – Unknown
                                        //• 1 – Personalization operation is in progress
                                        //• 2 – Ready
                                        //• 3 – Personalization code is required
                                        //• 4 – PUK for personalization code is required
                                        //• 5 – Permanently blocked
        BYTE perso_feature; //• 0 – GW network personalization
                                                //• 1 – GW network subset personalization
                                                //• 2 – GW service provider
                                                //personalization
                                                //• 3 – GW corporate personalization
                                                //• 4 – GW UIM personalization
                                                //• 5 – 1X network type 1 personalization
                                                //• 6 – 1X network type 2 personalization
                                                //• 7 – 1X HRPD personalization
                                                //• 8 – 1X service provider personalization
                                                //• 9 – 1X corporate personalization
                                                //• 10 – 1X RUIM personalization
                                                //• 11 – Unknown
        BYTE perso_retries;
        BYTE perso_unblock_retries;
        BYTE aid_len;
        CHAR aid_value[255];
        BYTE univ_pin;  //• 0 – PIN1 is used
                                        //• 1 – UPIN replaces PIN1
        BYTE pin1_state;//• 0 – Unknown
                                        //• 1 – Enabled and not verified
                                        //• 2 – Enabled and verified
                                        //• 3 – Disabled
                                        //• 4 – Blocked
                                        //• 5 – Permanently blocked
        BYTE pin1_retries;
        BYTE puk1_retries;
        BYTE pin2_state;//• 0 – Unknown
                                        //• 1 – Enabled and not verified
                                        //• 2 – Enabled and verified
                                        //• 3 – Disabled
                                        //• 4 – Blocked
                                        //• 5 – Permanently blocked
        BYTE pin2_retries;
        BYTE puk2_retries;
        //not supported
        //BYTE extended_hot_swap_len;
        //BYTE *extended_hot_swap;
        

        
}QMI_UIM_GET_CARD_STATUS_RESP_APPL; 

#define QMI_UIM_GET_CARD_STATUS_MAX_APPL 4
typedef struct
{
        BYTE card_state;
        BYTE upin_state;//0:unknown
                                        //1:enabled and not verified
                                        //2:enabled and verified
                                        //3:disabled
                                        //4:blocked
                                        //5:permanently blocked
        BYTE upin_retries;
        BYTE upuk_retries;
        BYTE error_code;//• 0 - Unknown
                                        //• 1 - Power down
                                        //• 2 - Poll error
                                        //• 3 - No ATR received
                                        //• 4 - Volt mismatch
                                        //• 5 - Parity error
                                        //• 6 - Unknown; possibly removed
                                        //• 7 - Card returned technical problems
                                        //Other values are possible and reserved
                                        //for future use. When an unknown value
                                        //is received, it is to be handled as
                                        //“Unknown”.
        BYTE num_app;
        QMI_UIM_GET_CARD_STATUS_RESP_APPL appls[QMI_UIM_GET_CARD_STATUS_MAX_APPL];
}QMI_UIM_GET_CARD_STATUS_RESP_SLOT;

#define QMI_UIM_GET_CARD_STATUS_MAX_SLOT 2
typedef struct {
        WORD            index_gw_pri;
        WORD            index_1x_pri;
        WORD            index_gw_sec;
        WORD            index_1x_sec;
        BYTE            num_slot;
        QMI_UIM_GET_CARD_STATUS_RESP_SLOT slots[QMI_UIM_GET_CARD_STATUS_MAX_SLOT];      
}QMI_UIM_GET_CARD_STATUS_RESP;

//QMI_UIM_STATUS_CHANGE_IND
#define QMI_UIM_CARD_STATUS QMI_UIM_GET_CARD_STATUS_RESP
#define QMI_UIM_STATUS_CHANGE_IND_RESP QMI_UIM_CARD_STATUS

//QMI_UIM_VERIFY_PIN_REQ
typedef struct
{
        BYTE            session_type;   //Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network.
                                                                //Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire a 1X/DO network.
                                                                //Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network (Dual Standby).
                                                                //Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire 1X/DO network (Dual
                                                                //Standby).
        BYTE            aid_len;
        BYTE            aid[255]; 
}QMI_UIM_VERIFY_PIN_REQ_SESSION_INFORMATION;
typedef struct
{
        BYTE            pin_id; //• 1 - PIN1 (also called PIN)
                                                //• 2 - PIN2
                                                //• 3 - Universal PIN
                                                //• 4 - Hidden key 
        BYTE            pin_len;
        char            pin_value[255];//ASCII
}QMI_UIM_VERIFY_PIN_REQ_VERIFY_PIN;
        
typedef struct 
{
        BYTE            verify_left;
        BYTE            unblock_left;
}QMI_UIM_VERIFY_PIN_RESP_RETRIES_REMAINING;

        
typedef struct
{
        BYTE            session_type;   //Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network.
                                                                //Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire a 1X/DO network.
                                                                //Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network (Dual Standby).
                                                                //Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire 1X/DO network (Dual
                                                                //Standby).
        BYTE            aid_len;
        BYTE            aid[255]; 
}QMI_UIM_UNBLOCK_PIN_REQ_SESSION_INFORMATION;

typedef struct
{
        BYTE            pin_id; //• 1 - PIN1 (also called PIN)
                                                //• 2 - PIN2
                                                //• 3 - Universal PIN
        BYTE            puk_len;
        char            puk_value[255];//ascii
        BYTE            new_pin_len;
        char            new_pin_value[255];
}QMI_UIM_UNBLOCK_PIN_REQ_UNBLOCK_PIN;

typedef struct
{
        BYTE            verify_left;
        BYTE            unblock_left;
}QMI_UIM_UNBLOCK_PIN_RESP_RETRIES_REMAINING;

typedef struct
{
        BYTE            session_type;   //Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network.
                                                                //Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire a 1X/DO network.
                                                                //Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network (Dual Standby).
                                                                //Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire 1X/DO network (Dual
                                                                //Standby).
        BYTE            aid_len;
        BYTE            aid[255]; 
}QMI_UIM_SET_PIN_PROTECTION_REQ_SESSION_INFORMATION;

typedef struct
{
                BYTE pin_id;    //• 1 - PIN1 (also called PIN)
                                                //• 2 - PIN2
                                                //• 3 - Universal PIN
                                                //• 4 - Hidden key
                BYTE pin_operation;//• 0 - disable the pin
                                                   //• 1 - enable the pin
                BYTE pin_len;
                char pin_value[255];
}QMI_UIM_SET_PIN_PROTECTION_REQ_SET_PIN_PROTECTION;

typedef struct
{
                BYTE            verify_left;
                BYTE            unblock_left;
}QMI_UIM_SET_PIN_PROTECTION_RESP_RETRIES_REMAINING;
        
        

typedef struct
{
        BYTE            session_type;   //Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network.
                                                                //Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire a 1X/DO network.
                                                                //Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
                                                                //(for UICC) used to acquire a GSM, a WCDMA or an
                                                                //LTE network (Dual Standby).
                                                                //Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
                                                                //(for UICC) used to acquire 1X/DO network (Dual
                                                                //Standby).
        BYTE            aid_len;
        BYTE            aid[255]; 
}QMI_UIM_CHANGE_PIN_REQ_SESSION_INFORMATION;

typedef struct
{
        BYTE            pin_id; //• 1 - PIN1 (also called PIN)
                                                //• 2 - PIN2
                                                //• 3 - Universal PIN
                                                //• 4 - Hidden key
        BYTE            old_pin_len;
        char            old_pin_value[255]; 
        BYTE            new_pin_len;
        char            new_pin_value[255]; 
}QMI_UIM_CHANGE_PIN_REQ_CHANGE_PIN;

typedef struct
{
                BYTE            verify_left;
                BYTE            unblock_left;
}QMI_UIM_CHANGE_PIN_RESP_RETRIES_REMAINING;

/*=========================================================================*/
// Callbacks
/*=========================================================================*/
typedef void (GOBICALLBACK * tFNUIMStatusChangeIndCallback)(
        //parameters
        QMI_UIM_CARD_STATUS* pCardStatus);


#ifdef __cplusplus
   };
#endif

/*=========================================================================*/
// Prototypes
/*=========================================================================*/
IMPORTGOBI ULONG GOBICMAPI UIMSetPINProtection(
        QMI_UIM_SET_PIN_PROTECTION_REQ_SESSION_INFORMATION *pSessionInformation,
        QMI_UIM_SET_PIN_PROTECTION_REQ_SET_PIN_PROTECTION* pSetPINProtection,
        QMI_UIM_SET_PIN_PROTECTION_RESP_RETRIES_REMAINING * pRetriesRemaining
        );


IMPORTGOBI ULONG GOBICMAPI UIMVerifyPIN(
        QMI_UIM_VERIFY_PIN_REQ_SESSION_INFORMATION *pSessionInformation,
        QMI_UIM_VERIFY_PIN_REQ_VERIFY_PIN* pVerifyPIN,
        QMI_UIM_VERIFY_PIN_RESP_RETRIES_REMAINING * pRetriesRemaining
        );


IMPORTGOBI ULONG GOBICMAPI UIMUnblockPIN(
        QMI_UIM_UNBLOCK_PIN_REQ_SESSION_INFORMATION *pSessionInformation,
        QMI_UIM_UNBLOCK_PIN_REQ_UNBLOCK_PIN* pUnblockPIN,
        QMI_UIM_UNBLOCK_PIN_RESP_RETRIES_REMAINING * pRetriesRemaining
        );


IMPORTGOBI ULONG GOBICMAPI UIMChangePIN(
        QMI_UIM_CHANGE_PIN_REQ_SESSION_INFORMATION *pSessionInformation,
        QMI_UIM_CHANGE_PIN_REQ_CHANGE_PIN* pChangePIN,
        QMI_UIM_CHANGE_PIN_RESP_RETRIES_REMAINING * pRetriesRemaining
        );


IMPORTGOBI ULONG GOBICMAPI UIMGetCardStatus(
        BOOL *pExtendedCardStatus,
        QMI_UIM_GET_CARD_STATUS_RESP* pCardStatus
        );


IMPORTGOBI ULONG GOBICMAPI SetUIMStatusChangeCallback( 
        tFNUIMStatusChangeIndCallback pCallback );


 // End of UIM group

#endif //GobiUimMgmtAPI_H